Skip to main content

FAQ & Troubleshooting

Common Questions​

What is the difference between a feature and a widget?​

A feature is a full-screen experience that appears as a new bottom tab (or in the More menu) in the mobile banking app. A widget is a component embedded in the existing home screen. Both use the same SDK (@cdx-extensions/di-sdk) and can leverage any SDK capability (useUserContext, useBranding, getHttpClient).

See Features Overview and Widgets Overview.

What is the mobile banking host app and who manages it?​

The mobile banking host application is the Candescent mobile app that loads and renders features in production. It is managed by the Candescent platform team. Features run inside this host app as embedded React Native packages — they are not standalone apps. Contact the Candescent technical support team to help integrate your developed feature with the mobile banking host.

How do I add my feature to the sandbox navigation?​

If you used the generator, your project is already registered in FEATURE_REGISTRY.tsx. See Mobile Playground — Feature Setup. If you created it manually, append a registry entry and rebuild.

My feature works in the sandbox but not in the production app.​

Run through this debugging checklist:

  • Package name matches: The npm package name (e.g. @acme-extensions/my-feature) must exactly match what the platform team registered for the host app.
  • Version matches: The release version must match what the host app expects.
  • Exports are correct: Your src/index.ts must export the component with both a named export and a default export.
  • Integration type matches: Confirm that the registered integration type is feature (not widget).
  • Peer dependencies satisfied: All peerDependencies declared in your package.json must be provided by the host app at the correct versions.
  • API domain is whitelisted: If your feature makes API calls, the target domain must be whitelisted in the platform's network configuration.
  • Build output is complete: Verify the package includes dist/index.js, dist/index.mjs, and dist/index.d.ts.

Shared mobile troubleshooting​

For Metro bundler errors, mock API setup, real API testing locally, useUserContext() mock data, branding switcher, and general sandbox issues, see the Mobile tab in Widgets FAQ.

Pre-Submission Checklist​

CheckHow to Verify
Renders without errorsRun npx nx start mobile-sandbox and open your feature from More / its tab
User context displays correctlyVerify the user name/email from userContext.json appears as expected
API calls return mock dataTrigger any data-fetching action and confirm the response matches apiResponses.json
Branding renders correctlyUse the gear icon to switch between branding variants
TypeScript compiles cleanlyRun npx nx run <name>:typecheck and confirm zero errors
Build output is correctRun npx nx run <name>:build and verify dist/ contains index.js, index.mjs, and index.d.ts

Recommendations​

DoDon't
Use sdk.getHttpClient() for all API callsUse raw fetch() or import Axios directly
Import SDK from @cdx-extensions/di-sdk onlyImport from @cdx-extensions/di-sdk-mobile in feature code
Use React Native StyleSheet for stylingUse web-specific CSS or MUI components
Keep peerDependencies aligned with those in the READMEChange React, React Native, or SDK versions independently
Export your component from src/index.ts with both named and default exportsForget the default export — some hosts use import Component from '...'

Next Steps​